Introduction - License - Installation - Building the library

JUCE

Introduction

JUCE is an all-encompassing C++ class library for developing cross-platform applications.

A complete doxygen-created API guide is available here as HTML, or can be downloaded as a precompiled Windows help file from the downloads page.

For more help and information, please visit the JUCE website.

License

JUCE is released under the Gnu Public License, which means it can be freely copied and distributed, and costs nothing to use in open-source applications.

If you'd like to release a closed-source application that uses JUCE, commercial licenses are available for a fee - click here for more information on pricing and terms.

Installation

Installing the source code

The JUCE source code all lives in a folder called, unsurprisingly, juce, which you can unzip and put somewhere on your system.

To compile the library, there is a subfolder juce/build that contains projects for different operating systems and compilers.

Building the demo application

Inside the juce folder is a demo application that shows off a few of Juce's features. The juce/demo/build folder contains projects and workspaces for the various platforms and compilers.

Building your application with JUCE

Compiling with Microsoft Visual C++ Express edition

To compile the JUCE .lib files from the source code:

Install the latest Platform SDK from Microsoft.

Set up your include and library search paths. The first few items on your include path should look like this (obviously you might have things installed in different places, but the order is important!):

C:\Program Files\Microsoft Platform SDK\include
C:\Program Files\Microsoft Platform SDK\include\crt
C:\Program Files\Microsoft Platform SDK\include\mfc
C:\mycode\juce
...

And the library search path should begin like this:

$(VSInstallDir)VC\lib
C:\Program Files\Microsoft Platform SDK\lib
C:\mycode\juce\bin
...

Open a solution and load juce/build/win32/vcexpress/JUCE.vcproj
There are several configurations: debug, release, debug-unicode, and release-unicode. You can build all or some of these, and the resultant .lib files should end up in the "juce/bin" folder.

Then, to create and build an application:

Either make a copy of the example project in juce/projects and rename/customise it, or create a new application project as an 'empty' WIN32 application - avoid saying yes to MFC or any of the other rubbish that Visual Studio might offer to pollute your application with.
Include the header file juce.h in all your source files (it's best to put this in a precompiled header).
Ensure that the linker's search path for libraries includes the the juce/bin directory. This path can be set globally, or can be added to your project's linker settings.
Choose to link to the "Multithreaded" or "Debug Multithreaded" run-time libraries, depending on whether you're doing a debug or release build. On VC6, this is set in the Project Settings / C/C++ / Code Generation options panel. In Visual Studio, it's in the project properties.
Make sure that your project has exception handling and run-time type information (RTTI) turned ON.
Have a look at the 'hello world' projects, demo projects, or the API documentation about the JUCEApplication class to find out how to create the application launch code.

Compiling with Microsoft Visual Studio 6

To compile the JUCE .lib files from the source code:

Install the latest Platform SDK from Microsoft.

C:\Program Files\Microsoft Platform SDK\include
C:\Program Files\Microsoft Platform SDK\include\crt
C:\Program Files\Microsoft Platform SDK\include\mfc
C:\mycode\juce
...

And the library search path should begin like this:

C:\Program Files\Microsoft Visual Studio\VC98\LIB
C:\Program Files\Microsoft Platform SDK\lib
C:\mycode\juce\bin
...

Open the juce.dsp project file in juce/build/win32/vc6
There are several configurations: debug, release, debug-unicode, and release-unicode. You can build all or some of these, and the resultant .lib files should end up in the "juce/bin" folder.

Note that there's a rather lame bug in VC6 that causes an internal compiler error if you include filenames that are too long. This can get triggered if you put the juce folder in a deeply-nested directory (such as your user home directory). Unfortunately I think the only workaround for this is to move the source tree to a shallower directory.

For info on building an application that links to Juce, see the VCExpress notes above above.

Compiling with XCode on MacOSX

To compile the JUCE binaries from the source code:

Open the Juce.xcodeproj file in juce/build/macosx
This project has "debug" and "release" configurations, and the library files it creates are libjuce.a (release) and libjucedebug.a (debug), which will appear in the juce/bin directory.

Then, to create and build an application:

Either make a copy of the example project in juce/projects and rename/customise it, or create a new "Carbon Application" project.
Include the header file juce.h in all your source files.
Get rid of any main() functions that XCode might have generated for you, and instead use the JUCEApplication class as your application launcher - see the API documentation for this class for more details, or have a look at the example projects, or demos.
Drag-and-drop the juce.xcodeproj file into the project's "External Frameworks and Libraries" list.
Expand this item in the treeview, and inside there'll be an item "libjuce.a" or "libjucedebug.a" - drag-and-drop this into the "link binary with libraries" phase inside the xcode target. When you select either a debug or release juce build these entries will (usually) update themselves to show the correct debug or release library name. If you want your project to automatically rebuild Juce when you make changes to a juce file, you can also add Juce to your target's "Direct Dependency" list (show information for the target, and this is on the "general" tab).
Alternative ways of linking to juce would be to add the libjuce.a or libjucedebug.a library to your "External Frameworks and Libraries" list, or to add switch to the linker's command-line of either "-ljuce" or "-ljucedebug".
You'll also need to add some of the following OSX frameworks to your "External Frameworks and Libraries" list, depending on what features your application uses:
```
Carbon.framework
IOKit.framework
CoreAudio.framework
CoreMIDI.framework
QuickTime.framework
OpenGL.framework
AGL.framework
```
In future there may be other frameworks that you'll need to link with to support new JUCE features. (It should be pretty obvious from the link-time error when one of these is missing).

Creating a JUCE application with Dev-C++

open \juce\build\win32\devcpp\juce.dev
You may need to install the Platform SDK from Microsoft, and add
```
C:\Program Files\Microsoft Platform SDK\Include
```
at the end of your include path to get some of the more recent header files.
Compile! It should produce a library file called juce/bin/libjuce.a

Then, to create and build an application:

Create a new project, as a "win32 GUI".
Remove main.cpp
Either copy the example main.cpp from the MSVC juce example project, or write your own based around the JUCEApplication class

In your project settings (alt-P), you'll need to adjust the linker's options so that it links the following libraries:

libjuce.a (this will be in your juce/bin/ directory)
libwininet.a
libdsound.a
libole32.a
libwinmm.a
libgdi32.a
libuuid.a
libshell32.a
libvfw32.a
librpcrt4.a (these are all in the Dev-C++ libraries folder)

Creating a JUCE application on Linux with GCC

Most linux distros should come with the tools you need, although you might want to get hold of premake, which is used to automatically generate the juce makefile. (This isn't necessary if you're just going to use the makefile that's provided).
Get a command prompt and go into /juce/build/linux
To build the debug version, use "make CONFIG=Debug", or use "make CONFIG=Release" to build the release version. You can also use "make clean" to delete the intermediate files.

Then, to create and build an application:

Building the library will have produced the library files /juce/bin/libjuce.a and /juce/bin/libjuce_debug.a. You'll need to link to one of these in your app, and you'll also need to link to these libraries:
```
freetype
pthread
X11
```
If you've set the JUCE_USE_XINERAMA flag in juce_Config.h, you'll also need to link to the xinerama library. And you'll need the GL and GLU libraries if you've enabled JUCE_OPENGL

***